클린 코드 - 주석, 포맷팅

주석

모든 내용을 주석으로 넣게 되면 코드가 지저분할 수 있습니다. 대부분은 좋은 Naming으로 충분히 해결이 가능합니다.

네이밍으로 표현할 수 없는 영역은 주석으로 표현해주면 됩니다

• 법적인 정보를 담을 때

  # Copyright (C) 2021 ...
  

• 의도를 명확하게 설명할 때

  # throughput을 늘리기 위해 스레드를 10개까지 늘린다.
  for idx in range(10):
      thread = threading.Thread(target=...)
      thread.start()
  ...
  

• 중요성을 강조할 때

  # 최종 결제를 하기 전에 진행해야 하는 validation 함수 
  def validate_buyable(wallet, price, ...):
      ...
  

• 결과를 경고할 때

  # WARNING: API 서버가 항상 양호한지 알 수 없음.
  def connect_api_server():
      ...
  

관용적으로 사용되는 키워드

TODO : 당장은 아니지만 다음에 해야 할 때

FIXME : 치명적인 에러를 발생하는 코드는 아니지만 수정해야 할 때

XXX : 더 생각해볼 필요가 있을 때

# TODO@grab: 객체의 책임 더 분리하기
class GrabStore:
    ...
    # FIXME: 반복문의 depth를 줄이기 
    def sell_food(self):
        for food in food_list:
            for discount in discount_list:
                ...

포맷팅

Vertical Formatting

• 한 파일에 코드를 다 넣지 말고, 개념에 맞게 파일을 나눠서 사용합니다.

  # as-is 
  # store.py에 전부 있음
  class FruitsStore:
      ...
  
  class ComputerStore:
      ...
  
  # to-be
  # fruit_store.py
  class FruitsStore:
      ...
  
  # computer_store.py
  class ComputerStore:
      ...
  

• 다른 개념의 코드는 Spacing으로 분리하기

• 비슷한 개념의 코드는 붙여서 사용하기

  def test_user_buy_product():
      user = User()
      product = Product()
      
      product.set_sold_out(True)
      user.get(product)
      
      assert result == "success"
  

Horizontal Formatting

• 한 줄에 코드를 다 넣기보단 변수 등을 활용해서 가독성 높이기

  #as-is
  product_list.extend([Product("모니터"), Product("키보드"), Product("노트북")])
  
  #to-be
  items = [Product("모니터"), Product("키보드"), Product("노트북")]
  product_list.extend(items)
  

• 네이밍 잘해서 길이 줄이기

  user_with_name_and_email = User("그랩", "grab@world.com")
  
  #to-be
  user = User("그랩", "grab@world.com")